detect_machine

A detection method that combines AMD (Answering Machine Detection) and fax detection. Detect whether the user on the other end of the call is a machine (fax, voicemail, etc.) or a human. The detection event(s) will be sent to the specified status_url as a POST request, and the current detection state or final result will also be saved in the detect_result variable.

Properties

objectRequired

An object that accepts the following properties.

detect_machine.detect_message_end

booleanDefaults to false

Whether to keep detecting after the call is classified as a machine. If false, detection can finish as soon as a machine is detected. If true, detection continues until a beep or the end of the voicemail greeting is detected, or until timeout. A detected beep ends detection either way.

detect_machine.detectors

stringDefaults to amd,fax

Comma-separated string of detectors to enable. Valid Values: amd, fax

detect_machine.end_silence_timeout

numberDefaults to 1.0

How long to wait for voice activity to finish (in seconds). Must be at least 1; smaller values, such as 0 or 0.5, are rejected.

detect_machine.initial_timeout

numberDefaults to 4.5

How long to wait for initial voice activity before giving up (in seconds). Must be at least 1; smaller values, such as 0 or 0.5, are rejected.

detect_machine.machine_ready_timeout

numberDefaults to value of the end_silence_timeout parameter

How long to wait for voice activity to finish before firing the READY event (in seconds). Must be at least 1; smaller values, such as 0 or 0.5, are rejected.

detect_machine.machine_voice_threshold

numberDefaults to 1.25

The number of seconds of ongoing voice activity required to classify as MACHINE. Must be at least 1; smaller values, such as 0 or 0.5, are rejected.

detect_machine.machine_words_threshold

integerDefaults to 6

The minimum number of words that must be detected in a single utterance before classifying the call as MACHINE. Must be at least 1; 0 is rejected.

detect_machine.status_url

string

The HTTP(S) URL to deliver detector events to. Learn more about status callbacks.

detect_machine.timeout

numberDefaults to 30.0

The maximum time to run the detector (in seconds).

detect_machine.tone

stringDefaults to CED

The tone to detect. Only the remote side tone will be received. (CED or CNG) Used for fax detection.

detect_machine.wait

booleanDefaults to true

If false, the detector will run asynchronously and status_url must be set. If true, the detector will wait for detection to complete before moving to the next SWML instruction.

Variables

The following variables are set when the detect_machine method returns. You can reference these variables in your SWML script utilizing the ${variable} syntax.

With wait: true (the default), they hold the final detection result. With wait: false, the method returns as soon as detection starts: detect_result is detecting, detect_machine_beep is false, and detect_ms is "-1". Later detection events go to status_url and do not update these variables.

detect_result

The lowercase SWML variable value for the current detection state or final result. failed means the detection request failed or returned no result. Callback lifecycle events such as READY, NOT_READY, and finished are never assigned to this variable.

detect_machine_beep

true | false

Whether a beep was detected. true if detected. Only reflects a completed measurement with wait: true. When detect_result is failed, this variable is not updated.

detect_ms

string

The number of milliseconds the detection took, stored as a string containing an integer (for example "3200"). "-1" when no duration is available, including with wait: false. When detect_result is failed, this variable is not updated.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url with a JSON payload like the following for each detection event:

event_type

string

The type of event: calling.call.detect for detection events.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing detection-specific parameters.

params.control_id

string

The control ID for this detect operation.

params.detect

object

Detection result details (see subfields below).

params.detect.type

string

The type of detection. Valid values: machine or fax.

params.detect.params

object

The detector event details.

params.detect.params.event

string

The detector event value in the status callback payload. The values depend on params.detect.type:

machine: detection outcome values are HUMAN, MACHINE, and UNKNOWN; lifecycle marker values are READY, NOT_READY, and finished.
fax: the detected fax tone, CNG or CED; the lifecycle marker finished marks the end of fax detection.

READY, NOT_READY, finished, CNG, and CED only appear in callback payloads and are not valid ${detect_result} values. The lowercase finished value is intentional.

params.detect.params.beep

boolean

Present and set to true when a beep was detected. Absent when no beep has been detected.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.segment_id

string

The segment ID for this part of the call.

If the detection request fails, status_url can instead receive an event with event_type set to calling.error. Its params holds an error object that describes the failure and a request object with the request that failed, in place of params.detect.

Raw JSON example

{
  "event_type": "calling.call.detect",
  "event_channel": "swml:be38xxxx-8xxx-4xxxx-9fxx-bxxxxxxxxx",
  "timestamp": 1745332535.668522,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "detect": {
      "type": "machine",
      "params": {
        "event": "MACHINE",
        "beep": true
      }
    },
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Examples

Play the detection result

version: 1.0.0
sections:
  main:
    - detect_machine:
        status_url: 'https://example.com/detect-events'
        timeout: 20
    - play:
        url: 'say:Detection result: ${detect_result}'

Conditional actions based on the detection result

version: 1.0.0
sections:
  main:
    - play:
        url: "say: Welcome to the machine detection test."
    - detect_machine:
        status_url: "https://webhook.site/5c8abf82-b8c7-41c8-b5d6-b32a40068109"
        detectors: "amd,fax"
        wait: true
    - cond:
        - when: detect_result == 'machine'
          then:
            - play:
                url: "say: You are a machine, goodbye."
            - hangup: {}
        - when: detect_result == 'human'
          then:
            - play:
                url: "say: You are a human, hello."
            - hangup: {}
        - when: detect_result == 'fax'
          then:
            - play:
                url: "say: You are a fax, goodbye."
            - hangup: {}
        - else:
            - play:
                url: "say: Unable to determine if you are a human, machine, or fax, goodbye. Result was ${detect_result}"
            - hangup: {}